Scripting
开始
文档
更新日志
隐私
开始
文档
更新日志
隐私
简体中文

读取活动摘要（HealthActivitySummary）

Scripting 应用通过全局函数 Health.queryActivitySummaries() 提供对 Apple Health 每日活动摘要数据的访问。这些摘要包含 Apple Watch 追踪的 移动（Move）、锻炼（Exercise） 和 站立（Stand） 目标，以及完成情况和历史趋势。

此 API 非常适合在应用中展示每日活动环或分析长期健身趋势。

什么是活动摘要？

HealthActivitySummary 提供一天 Apple Watch 活动的概览：

  • 移动（活跃能量消耗）

    • activeEnergyBurned(unit: HealthUnit): number
    • activeEnergyBurnedGoal(unit: HealthUnit): number

  • 锻炼（分钟）

    • appleExerciseTime(unit: HealthUnit): number
    • appleExerciseTimeGoal(unit: HealthUnit): number

  • 站立（小时）

    • appleStandHours(unit: HealthUnit): number
    • appleStandHoursGoal(unit: HealthUnit): number

  • 日期信息

    • dateComponents: DateComponents —— 包含 year、month、day 的 DateComponents 对象

API 概览

1Health.queryActivitySummaries(
2  options?: {
3    start: DateComponents
4    end: DateComponents
5  }
6): Promise<HealthActivitySummary[]>

参数

参数 类型 说明
start DateComponents 查询范围的起始日期，仅返回在该日期或之后的摘要。
end DateComponents 查询范围的结束日期，仅返回在该日期或之前的摘要。

如果同时省略 options，则返回所有可用摘要（受系统限制）。 返回的摘要按日期升序排序。

示例：读取最近 7 天的活动摘要

1async function fetchLastWeek() {
2  // 构建日期范围
3  const today = new Date()
4  const sevenDaysAgo = new Date(
5    today.getFullYear(),
6    today.getMonth(),
7    today.getDate() - 6
8  )
9
10  const startComponents = DateComponents.fromDate(sevenDaysAgo)
11  const endComponents = DateComponents.fromDate(today)
12
13  // 查询活动摘要
14  const summaries = await Health.queryActivitySummaries({
15    start: startComponents,
16    end: endComponents,
17  })
18
19  // 遍历并打印每天数据
20  for (const summary of summaries) {
21    const date = summary.dateComponents.date
22    console.log(`日期: ${date?.toDateString()}`)
23
24    const kcal = summary.activeEnergyBurned(HealthUnit.kilocalorie())
25    const kcalGoal = summary.activeEnergyBurnedGoal(HealthUnit.kilocalorie())
26    const exerciseMin = summary.appleExerciseTime(HealthUnit.minute())
27    const standHrs = summary.appleStandHours(HealthUnit.count())
28
29    console.log(` 移动:    ${kcal} / ${kcalGoal} kcal`)
30    console.log(` 锻炼:    ${exerciseMin} 分钟`)
31    console.log(` 站立:    ${standHrs} 小时`)
32    console.log('---')
33  }
34}
35
36fetchLastWeek()

注意事项

  • DateComponents 至少需包含 year、month、day，其他字段（如小时、分钟）在日摘要中会被忽略。
  • 各项指标方法均返回所指定单位下的原始 number 值。
  • 使用 HealthUnit 工厂方法（如 kilocalorie()、minute()、count()）来指定单位。
  • 如果某些日期没有数据（例如 Apple Watch 未佩戴或未同步），则该日期的摘要可能会被省略。

总结

  1. 调用 Health.queryActivitySummaries({ start, end }) 并传入 DateComponents 指定查询范围。
  2. 获取按日期升序排列的 HealthActivitySummary[]。
  3. 调用摘要实例的方法读取移动、锻炼和站立的实际值及目标值。
  4. 在 UI 或分析中展示或统计这些数字。
大纲